---
description: Mantenga un changelog
title: Mantenga un changelog
language: es-ES
version: 1.0.0
---

- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
- gh = "https://github.com/olivierlacan/keep-a-changelog"
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
- semver = "https://semver.org/"
- shields = "https://shields.io/"
- thechangelog = "https://changelog.com/podcast/127"
- vandamme = "https://github.com/tech-angels/vandamme/"
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
- ghr = "https://help.github.com/articles/creating-releases/"

.header
  .title
    %h1 Mantenga un changelog
    %h2
      No dejes que tus amigos usen el registro de git en los changelogs.

  = link_to changelog do
    Versión
    %strong= current_page.metadata[:page][:version]

  %pre.changelog= File.read("CHANGELOG.md")

.answers
  %h3#what
    %a.anchor{ href: "#what", aria_hidden: "true" }
    ¿Qué es un registro de cambios (changelog)?

  %p
    Un registro de cambios, «changelog» de ahora en adelante, es un
    archivo que contiene una lista cronológicamente ordenada de los
    cambios más destacables para cada versión de un proyecto.

  %h3#why
    %a.anchor{ href: "#why", aria_hidden: "true" }
    ¿Por qué mantener un changelog?

  %p
    Para facilitar a los usuarios y colaboradores ver exactamente qué
    cambios reseñables se han realizado entre cada versión del
    proyecto.

  %h3#who
    %a.anchor{ href: "#who", aria_hidden: "true" }
    ¿Quién necesita un changelog?

  %p
    Las personas. Ya sean consumidores o desarrolladores, los usuarios
    finales del software son seres humanos a los que le importa lo que
    hay en el software. Cuando el software cambia, la gente quiere saber
    el porqué y el cómo.

.good-practices
  %h3#how
    %a.anchor{ href: "#how", aria_hidden: "true" }
    ¿Cómo hago un buen changelog?

  %h4#principles
    %a.anchor{ href: "#principles", aria_hidden: "true" }
    Directrices

  %ul
    %li
      Están hechos <em>para los seres humanos</em>, no para las máquinas.
    %li
      Debe haber una entrada para cada versión.
    %li
      Los mismos tipos de cambios deben ser agrupados.
    %li
      Versiones y secciones deben ser enlazables.
    %li
      La última versión va primero.
    %li
      Debe mostrar la fecha de publicación de cada versión.
    %li
      Indicar si el proyecto sigue el #{link_to "Versionamiento Semántico", semver}.

  %a.anchor{ href: "#types", aria_hidden: "true" }
  %h4#types Tipos de cambios

  %ul
    %li
      %code Added
      para funcionalidades nuevas.
    %li
      %code Changed
      para los cambios en las funcionalidades existentes.
    %li
      %code Deprecated
      para indicar que una característica o funcionalidad está obsoleta
      y que se eliminará en las próximas versiones.
    %li
      %code Removed
      para las características en desuso que se eliminaron en esta
      versión.
    %li
      %code Fixed
      para corrección de errores.
    %li
      %code Security
      en caso de vulnerabilidades.

.effort

  %h3#effort
    %a.anchor{ href: "#effort", aria_hidden: "true" }
    ¿Cómo puedo minimizar el esfuerzo requerido para mantener el
    changelog?

  %p
    Mantén una sección con el nombre <code>Unreleased</code> para hacer
    un seguimiento sobre los próximos cambios.

  %p Esto nos puede servir para dos cosas:

  %ul
    %li
      La gente puede ver qué cambios podrían esperar en los próximos
      lanzamientos.
    %li
      Al lanzar una nueva versión, tan sólo habría que mover el
      contenido de <code>Unreleased</code> a una sección para la nueva
      versión.

.bad-practices
  %h3#bad-practices
    %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
    ¿Pueden los changelogs ser malos?

  %p
    Sí. A continuación algunas formas en las que pueden ser muy poco
    útiles.

  %h4#log-diffs
    %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
    Usar un diff de los logs de los commits

  %p
    Usar un diff de los logs de los commits es una mala idea: están
    llenos de ruido. Cosas como hacer <em>merge</em> de los commits,
    commits con títulos poco claros, cambios de documentación, etc.

  %p
    El propósito de un commit es documentar un paso en la evolución del
    código fuente. Algunos proyectos limpian los commits, otros no.

  %p
    El propósito de una entrada en el changelog es documentar cambios
    notables, usualmente entre múltiples commits, para comunicarlos
    claramente a los usuarios finales.

  %h4#ignoring-deprecations
    %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
    Ignorar <em>funcionalidades sin soporte</em>

  %p
    Cuando la gente actualiza de una version a otra, debería estar
    bastante claro cuándo algo se va a romper. Debería ser posible
    actualizar a una versión que detalle funcionalidades sin soporte,
    eliminar lo que está obsoleto y actualizar a la versión donde esas
    funcionalidades han sido eliminadas.
  %p
    Si no haces nada más, enumera lo que queda obsoleto, lo eliminado y
    cualquier otro cambio sin compatibilidad hacia atrás en tu
    changelog.

  %h4#confusing-dates
    %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
    Fechas confusas

  %p
    Los formatos de fecha regionales varían en todo el mundo y con
    frecuencia es difícil encontrar un formato intuitivo para todos. La
    ventaja de las fechas con el formato <code>2017-07-17</code> es que
    siguen un orden de unidades de mayor a menor: año, mes y día. Este
    formato tampoco coincide de forma ambigua con otros formatos de
    fecha, a diferencia de algunos que intercambian la posición del mes
    y el día. Todo esto, junto al hecho de ser un
    #{link_to "estándar ISO", iso}, son los motivos por los que es el
    formato de fecha recomendado para las entradas del changelog.

  %aside
    Hay más. Ayúdame a recoger estos anti-patrones
    = link_to "abriendo un issue", "#issues"
    o una <em>pull request</em>.

.frequently-asked-questions
  %h3#frequently-asked-questions
    %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
    Preguntas frecuentes

  %h4#standard
    %a.anchor{ href: "#standard", aria_hidden: "true" }
    ¿Hay un formato estándar para el changelog?

  %p
    No. Hay una guía de estilo del GNU o los dos parrafos del archivo
    <code>guideline</code> del <em>GNU NEWS</em>. Ambos son inadecuados
    o insuficientes.

  %p
    Este proyecto apunta a ser
    = link_to "una mejor convención de changelog.", changelog
    Esto se da observando las buenas prácticas en la comunidad open
    source y recopilando las mismas.

  %p
    Críticas saludables, discusión y sugerencias para mejoras
    = link_to "son bienvenidas.", issues


  %h4#filename
    %a.anchor{ href: "#filename", aria_hidden: "true" }
    ¿Cómo debería llamarse el archivo de changelog?

  %p
    Llámalo <code>CHANGELOG.md</code>. Algunos proyectos utilizan
    <code>HISTORY</code>, <code>NEWS</code> o <code>RELEASES</code>.

  %p
    Si bien es fácil pensar que el nombre de tu archivo de changelog no
    importa tanto, ¿Por qué hacer difícil para los usuarios finales
    conseguir de manera consistente los cambios notables?

  %h4#github-releases
    %a.anchor{ href: "#github-releases", aria_hidden: "true" }
    ¿Y qué hay de los releases de Github?

  %p
    Es una gran iniciativa. #{link_to "Los releases de Github", ghr}
    pueden ser utilizados para convertir simples etiquetas de git (por
    ejemplo una etiqueta llamada <code>v1.0.0</code>) en ricas notas de
    lanzamiento ya sea añadiendo estas manualmente o trayendo los
    mensajes anotados de las etiquetas de git y convertirlas en notas.

  %p
    Los releases de Github crean un changelog no portable que sólo
    pueden ser mostrados a usuarios dentro del contexto de Github. Es
    posible hacer que luzcan muy parecidas al formato de <em>Mantenga un
    changelog</em>, pero tiende a ser un poco más complicado.

  %p
    La versión actual de los releases de Github es también
    discutiblemente no muy detectable por los usuarios finales,
    diferente a los típicos archivos en mayúsculas (<code>README</code>,
    <code>CONTRIBUTING</code>, etc.). Otro problema menor es que la
    interfaz actualmente no ofrece enlaces a los registros de los
    commits entre cada lanzamiento.

  %h4#automatic
    %a.anchor{ href: "#automatic", aria_hidden: "true" }
    ¿Se pueden analizar gramaticalmente los changelogs?

  %p
    Es difícil, porque las personas usan formatos y nombres de archivos
    muy distintos.

  %p
    #{link_to "Vandamme", vandamme} es una gema de Ruby creada por el
    equipo de Gemnasium que analiza
    gramaticalmente muchos (pero no todos) los changelogs de proyectos
    open source.


  %h4#yanked
    %a.anchor{ href: "#yanked", aria_hidden: "true" }
    ¿Qué hay sobre las versiones retiradas?

  %p
    «Yanked releases» son versiones que tuvieron que ser retiradas por
    un error grave o problema de seguridad. Con frecuencia estas
    versiones ni siquiera aparecen en los changelogs. Deberían. Así es
    como deberían mostrarse:

  %p <code>## [0.0.5] - 2014-12-13 [YANKED]</code>

  %p
    La etiqueta <code>[YANKED]</code> está destacada por una razón: es
    importante que destaque. El hecho de estar entre corchetes la hace
    también más fácil de localizar programáticamente.


  %h4#rewrite
    %a.anchor{ href: "#rewrite", aria_hidden: "true" }
    ¿Deberías volver a escribir un changelog?

  %p
    Por supuesto. Siempre hay buenas razones para mejorar el changelog.
    A veces abro «pull requests» para añadir registros faltantes en el
    changelog de proyectos open source.

  %p
    También es posible que puedas descubrir que olvidaste señalar un
    cambio sin compatibilidad hacia atrás en las notas para una versión.
    En este caso es importante para ti actualizar el changelog.


  %h4#contribute
    %a.anchor{ href: "#contribute", aria_hidden: "true" }
    ¿Cómo puedo contribuir?

  %p
    Este documento no es la <strong>verdad absoluta</strong>; es mi
    cuidadosa opinión, junto con información y ejemplos que recopilé.

  %p
    Esto es porque quiero que la comunidad llegue a un consenso. Creo
    que la discusión es tan importante como el resultado final.

  %p
    Así que por favor <strong>#{link_to "comienza a colaborar", gh}
    </strong>.

.press
  %h3 Conversaciones
  %p
    Fui a #{link_to "The Changelog podcast", thechangelog} para hablar
    acerca del porqué los mantenedores y colaboradores deberían
    preocuparse por los changelogs, y también acerca de las motivaciones
    detrás de este proyecto.
